# React 插件

import { SourceCode } from 'rspress/theme';

<SourceCode href="https://github.com/web-infra-dev/rsbuild/tree/main/packages/plugin-react" />

React 插件提供了对 React 的支持，插件内部集成了 JSX 编译、React Refresh 等功能。

## 快速开始

### 安装插件

你可以通过如下的命令安装插件:

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs command="add @rsbuild/plugin-react -D" />

### 注册插件

你可以在 `rsbuild.config.ts` 文件中注册插件：

```ts title="rsbuild.config.ts"
import { pluginReact } from '@rsbuild/plugin-react';

export default {
  plugins: [pluginReact()],
};
```

注册插件后，你可以直接进行 React 开发。

## 选项

### swcReactOptions

用于配置 SWC 转换 React 代码的行为，等价于 SWC 的 [jsc.transform.react](https://swc.rs/docs/configuration/compilation#jsctransformreact) 选项。

- **类型：**

```ts
interface SwcReactOptions {
  pragma?: string;
  pragmaFrag?: string;
  throwIfNamespace?: boolean;
  development?: boolean;
  useBuiltins?: boolean;
  refresh?: boolean;
  runtime?: 'automatic' | 'classic';
  importSource?: string;
}
```

- **默认值：**

```ts
const isDev = process.env.NODE_ENV === 'development';
const defaultOptions = {
  development: isDev,
  refresh: isDev,
  runtime: 'automatic',
};
```

### swcReactOptions.runtime

设置 JSX runtime 的类型。

- **类型：** `'automatic' | 'classic'`
- **默认值：** `'automatic'`

默认情况下，Rsbuild 使用 React 17 引入的[新版本 JSX runtime](https://legacy.reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html)，即 `runtime: 'automatic'`。

如果你当前的 React 版本低于 16.14.0，可以将 `runtime` 设置为 `'classic'`：

```ts
pluginReact({
  swcReactOptions: {
    runtime: 'classic',
  },
});
```

> React 16.14.0 可以使用新版本 JSX runtime。

在使用 classic JSX runtime 时，你需要手动在代码中引入 React：

```jsx
import React from 'react';

function App() {
  return <h1>Hello World</h1>;
}
```

### swcReactOptions.importSource

当 `runtime` 为 `'automatic'` 时，你可以通过 `importSource` 来指定 JSX runtime 的引入路径。

- **类型：** `string`
- **默认值：** `'react'`

比如，在使用 [Emotion](https://emotion.sh/) 时，你可以将 `importSource` 设置为 `'@emotion/react'`：

```ts
pluginReact({
  swcReactOptions: {
    importSource: '@emotion/react',
  },
});
```

### splitChunks

在 [chunkSplit.strategy](/config/performance/chunk-split) 设置为 `split-by-experience` 时，Rsbuild 默认会自动将 `react` 和 `router` 相关的包拆分为单独的 chunk:

- `lib-react.js`：包含 react，react-dom，以及 react 的子依赖（scheduler）。
- `lib-router.js`：包含 react-router，react-router-dom，以及 react-router 的子依赖（history，@remix-run/router）。

该选项用于控制这一行为，决定是否需要将 `react` 和 `router` 相关的包拆分为单独的 chunk。

- **类型：**

```ts
type SplitReactChunkOptions = {
  react?: boolean;
  router?: boolean;
};
```

- **默认值：**

```ts
const defaultOptions = {
  react: true,
  router: true,
};
```

- **示例：**

```ts
pluginReact({
  splitChunks: {
    react: false,
    router: false,
  },
});
```

### enableProfiler

- **类型：** `boolean`
- **默认值：** `false`

当设置为 `true` 时，在生产构建中启用 React 性能分析器以用于性能分析。需要搭配 React DevTools 来检查分析结果并识别潜在的性能优化方案。分析会增加一些额外开销，因此出于性能考虑，在生产环境中默认是禁用的。

```ts title="rsbuild.config.ts"
pluginReact({
  // 仅在 REACT_PROFILER 为 true 时启用性能分析器
  // 因为该选项会增加构建时间并产生一些额外开销
  enableProfiler: process.env.REACT_PROFILER === 'true',
});
```

执行构建脚本时，设置 `REACT_PROFILER=true` 即可：

```bash
REACT_PROFILER=true npx rsbuild build
```

> 关于使用 React DevTools 进行性能分析的详细信息，请参见 [React 文档](https://legacy.reactjs.org/docs/optimizing-performance.html#profiling-components-with-the-devtools-profiler)。

### reactRefreshOptions

- **类型：**

```ts
type ReactRefreshOptions = {
  include?: string | RegExp | (string | RegExp)[] | null;
  exclude?: string | RegExp | (string | RegExp)[] | null;
  library?: string;
  forceEnable?: boolean;
};
```

- **默认值：**

```js
const defaultOptions = {
  include: [/\.(?:js|jsx|mjs|cjs|ts|tsx|mts|cts)$/],
};
```

设置 [@rspack/plugin-react-refresh](https://www.rspack.dev/guide/tech/react#rspackplugin-react-refresh) 的选项，传入的值会与默认值进行浅合并。

- **示例：**

```js
pluginReact({
  reactRefreshOptions: {
    exclude: [/some-module-to-exclude/],
  },
});
```
